home *** CD-ROM | disk | FTP | other *** search
/ HyperLib 1997 Winter - Disc 1 / HYPERLIB-1997-Winter-CD1.ISO.7z / HYPERLIB-1997-Winter-CD1.ISO / オンラインウェア / UTIL / ES 1.2 Package.sit / ES 1.2 Package / Developer’s toolkit / Headers / ExtensionsStrip.h next >
Text File  |  1995-12-09  |  15KB  |  371 lines
  1. /*
  2.      File:        ExtensionsStrip.h
  3.  
  4.      Contains:    Extensions Strip Specific Interfaces for Control Strip modules.
  5.  
  6.      Version:    Technology:    System 7.1+ (System 7.5+ preferred)
  7.                  Package:    Extensions Strip 1.2
  8.  
  9.      Copyright:    ｩ 1995 by Ammon Skidmore, Skidperfect Software Inc.
  10.                  All rights reserved.
  11.  
  12.      Bugs?:        If you find a problem, have a criticism or comment with this
  13.                  file, please inform the author at the following address:
  14.                      Internet:    skidperfect@kagi.com
  15. */
  16.  
  17. #ifndef __EXTENSIONSSTRIP__
  18. #define __EXTENSIONSSTRIP__
  19.  
  20. #ifndef __CONTROLSTRIP__
  21. #include <ControlStrip.h>
  22. #endif
  23.  
  24. #ifndef __APPLEEVENTS__
  25. #include <AppleEvents.h>
  26. #endif
  27.  
  28. #ifdef __cplusplus
  29. extern "C" {
  30. #endif
  31.  
  32. #if PRAGMA_ALIGN_SUPPORTED
  33. #pragma options align=mac68k
  34. #endif
  35.  
  36. #if PRAGMA_IMPORT_SUPPORTED
  37. #pragma import on
  38. #endif
  39.  
  40.  
  41. /******************************************************************************************
  42.  
  43.     Special Extensions Strip selector calls to modules.
  44.  
  45. ******************************************************************************************/
  46. enum {
  47.     sdevInAppContext            = 2000,    /* called only once after the module specifically
  48.                                            requested to be executed from inside Extension
  49.                                            Strip's context. NB: you can return the special
  50.                                            result values. */
  51.  
  52.     sdevInterceptedEvent        = 2001,    /* if the module returned the sdevInterceptAllEvents
  53.                                            flag in its features, then this selector
  54.                                            will get called before _each_ event is processed
  55.                                            by Extensions Strip.  Meant to be used with
  56.                                            _SBGetCurrentEvent so each event can be looked at,
  57.                                            and modified if necessary (to prevent passing.)
  58.                                            NB: you can return the special result values. */
  59.  
  60.     sdevDragAccept                = 2002,    /* return 0 if you accept the current drag, and
  61.                                            1 if you do not.  Modules that do not have any
  62.                                            drag handlers will never get this called.
  63.                                            NB: sdevDragAccept is only called from within
  64.                                            Extensions Strip's dragTrackingInWindow.  So it
  65.                                            is recommended to only check if you accept the
  66.                                            drag from within your dragTrackingEnterWindow, and
  67.                                            then set a global var that you can pass onto ES */
  68.  
  69.     sdevEventMask                = 2003    /* if the module returned the sdevInterceptAllEvents
  70.                                            flag in its features, this selector will get
  71.                                            called to find the event mask to use.  Return your
  72.                                            mask as the result value of the sdev call.
  73.                                            sdevEventMask is called once upon initialization,
  74.                                            and every time sdevFeaturesChange is requested. */
  75. };
  76.  
  77. /******************************************************************************************
  78.  
  79.     Features supported by the module.  If a bit is set, it means that feature is supported.
  80.  
  81.     Tip: if you clear sdevWantMouseClicks and set sdevDontAutoTrack, your module
  82.     will receive clicks and Extensions Strip (plus Desktop Strip) will not
  83.     auto-hilite your module.
  84.  
  85. ******************************************************************************************/
  86. enum {
  87.     sdevHasDragHandlers            = 31,    /* module has installed a drag tracking and/or
  88.                                            receive handler in the Strip window. */
  89.  
  90.     sdevDontPeriodicTickle        = 30,    /* module does not require any idle time so
  91.                                            by setting this bit it will never get
  92.                                            called with the sdevPeriodicTickle 
  93.                                            selector.  Note that you can set this along
  94.                                            with the sdevInterceptAllEvents bit (if you want)
  95.                                            and sdevInterceptedEvent will still get called.
  96.                                            So be nice and set this to help speed up idle
  97.                                            time processing. */
  98.  
  99.     sdevInterceptAllEvents        = 29    /* module wants to be executed before each
  100.                                            event passes through Extension Strip's
  101.                                            jGNE filter.  Because the module is allowed
  102.                                            to modify every event, there is no more need
  103.                                            for modules, such as Terminator Strip, to
  104.                                            install their own jGNE filters!
  105.                                            NB: You need to return an event mask when your
  106.                                            module is called by the sdevEventMask selector. */
  107. };
  108.  
  109. /******************************************************************************************
  110.  
  111.     Special result values returned by the sdevPeriodicTickle and sdevMouseClick selectors.
  112.     If a bit is set, the module can request that a specific function is performed by
  113.     the Control Strip.  All undefined bits should be set to zero.
  114.  
  115.     Note: these values can also be returned by the sdevInAppContext and
  116.     sdevInterceptedEvent selectors.
  117.  
  118. ******************************************************************************************/
  119. enum {
  120.     sdevQueueModule                = 31,    /* module needs to be executed from within
  121.                                            Extension Strip's context: useful for
  122.                                            things like sending AppleEvents or
  123.                                            creating and tracking new drags. */
  124.  
  125.     sdevFeaturesChange            = 30    /* module wants to change its feature flags. Useful
  126.                                            for changing clickable state of the module and
  127.                                            for locking/unlocking the sdev code. */
  128. };
  129.  
  130. /******************************************************************************************
  131.  
  132.     miscellaneous
  133.  
  134. ******************************************************************************************/
  135. enum {
  136.     kModuleFolderType                = 'sdev',    /* FindFolder type for the root folder */
  137.     kModuleDisabledFolderType        = 'sdeD',    /* FindFolder type for the disabled
  138.                                                    root folder (place to put inactive
  139.                                                    modules that you don't want deleted.) */
  140.     sdevTypeCodePPC                    = 'Sdev'    /* resource type for PPC module code */
  141. };
  142.  
  143.  
  144. enum {
  145.     gestaltExtensionsStripAttr        = 'CsEs',    /* returns Extensions Strip's attributes. */
  146.     /* currently returned bits from gestaltExtensionsStripAttr: */
  147.     gestaltExtensionsStripExists    = 0,        /* Extensions Strip is currently launched */
  148.     gestaltSupportsFontTraps        = 1,        /* The new font traps of Control Strip 1.2
  149.                                                    are supported.  ES 1.0 incorrectly gave
  150.                                                    Control Strip's font trap gestalt bit. */
  151.     gestaltHasSBResolveAliasFile    = 2,        /* ES contains the new alias resolving trap.
  152.                                                    This bit also signifies that ES can only
  153.                                                    be run as a regular application. */
  154.  
  155.     gestaltDesktopStripAttr            = 'CsWT'    /* returns the Desktop Strip program
  156.                                                    attributes which are supported by
  157.                                                    Extensions Strip.  See Desktop Strip's
  158.                                                    docs for details about the bits */
  159. };
  160.  
  161.  
  162. typedef unsigned long ModuleReference;
  163.  
  164.  
  165. typedef pascal void (*SBQueueProcPtr)(unsigned long refCon);
  166.  
  167. #if GENERATINGCFM
  168. typedef UniversalProcPtr SBQueueUPP;
  169. #else
  170. typedef SBQueueProcPtr SBQueueUPP;
  171. #endif
  172.  
  173. enum {
  174.     uppQueueProcProcInfo = kPascalStackBased | STACK_ROUTINE_PARAMETER(1, kFourByteCode)
  175. };
  176.  
  177. #if GENERATINGCFM
  178. #define NewSBQueueProcProc(userRoutine)        ¥
  179.         (SBQueueUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppAEIdleProcInfo, GetCurrentArchitecture())
  180. #else
  181. #define NewSBQueueProcProc(userRoutine)        ¥
  182.         ((SBQueueUPP) (userRoutine))
  183. #endif
  184.  
  185. /******************************************************************************************
  186.  
  187.     Control Strip trap calls
  188.  
  189. ******************************************************************************************/
  190.  
  191. //                                                                                 //
  192. // All routines are documented as to whether the Extensions Strip implementation //
  193. // of them they may move memory.  You can trust that a routine that says it         //
  194. // will not move memory in this version, will not move memory in future versions.//
  195. // Note though, that some Universal Control Strip traps may move memory under     //
  196. // Control/Desktop Strip but not in Extensions Strip (such as                     //
  197. // _SBIsControlStripVisible and _SBShowHideControlStrip.)                         //
  198. //                                                                                 //
  199.  
  200. // =====================================================
  201. // =========== Universal Control Strip traps ===========
  202. // =====================================================
  203. /*
  204. 'Yes' = May move memory!
  205. 'No'  = Will not move memory.
  206. 'unimplemented'    = Trap not supported by Extensions Strip when this header file
  207.                 was released.  Check the Control Strip gestalt features to
  208.                 determine if/when Extensions Strip supports these traps.
  209.  
  210. SBIsControlStripVisible        no
  211. SBShowHideControlStrip        no
  212. SBSafeToAccessStartupDisk    no
  213. SBOpenModuleResourceFile    yes
  214. SBLoadPreferences            yes
  215. SBSavePreferences            yes
  216. SBGetDetachedIndString        no
  217. SBGetDetachIconSuite        yes
  218. SBTrackPopupMenu            yes
  219. SBTrackSlider                yes
  220. SBShowHelpString            yes
  221. SBGetBarGraphWidth            no
  222. SBDrawBarGraph                yes
  223. SBModalDialogInContext        yes
  224.  
  225. Control Strip 1.2 and later
  226. ---------------------------
  227. SBGetControlStripFontID        no
  228. SBSetControlStripFontID        no
  229. SBGetControlStripFontSize    no
  230. SBSetControlStripFontSize    no
  231. SBGetShowHideHotKey            unimplemented
  232. SBSetShowHideHotKey            unimplemented
  233. SBIsShowHideHotKeyEnabled    unimplemented
  234. SBEnableShowHideHotKey        unimplemented
  235. */
  236.  
  237. // =====================================================
  238. // ========== Extensions Strip specific traps ==========
  239. // =====================================================
  240.  
  241. /* Strip Window Utilities */
  242.  
  243.     // returns: true = vertical; false = horizontal
  244.     //        // Will not move memory. //
  245. extern pascal Boolean SBIsControlStripVertical(WindowRef stripPort)
  246.  TWOWORDINLINE(0x70FF, 0xAAF2);
  247.  
  248.     // returns pixel depth of the monitor this Strip window is in (always a power of 2)
  249.     //        // Will not move memory. //
  250. extern pascal short SBGetControlStripDepth(WindowRef stripPort)
  251.  TWOWORDINLINE(0x70FE, 0xAAF2);
  252.  
  253.     // returns the current normal back color of this Strip window
  254.     //        // Will not move memory. //
  255. extern pascal void SBGetStripBackColor(RGBColor *color, WindowRef stripPort)
  256.  TWOWORDINLINE(0x70FD, 0xAAF2);
  257.  
  258.     //returns the current back color of this Strip window when a module is selected
  259.     //        // Will not move memory. //
  260. extern pascal void SBGetStripSelectedColor(RGBColor *color, WindowRef stripPort)
  261.  TWOWORDINLINE(0x70FC, 0xAAF2);
  262.  
  263. /* Module Utilities */
  264.  
  265.     // returns a reference number that all of the Module Utilities need
  266.         /* NB: since SBGetMyReferenceNum can ONLY be called from sdevInitModule,
  267.            you should save its value into your globals if you are going to use
  268.            one of the Module Utilities later, such as inside a tracking handler. */
  269.     // Also, the reference number will always be non-zero.
  270.     //        // Will not move memory. //
  271. extern pascal ModuleReference SBGetMyReferenceNum(void)
  272.  TWOWORDINLINE(0x70FB, 0xAAF2);
  273.  
  274.     // total window space taken up by a module.  Useful for drag-n-drop calculations
  275.     // note that this rect will always be larger than the module's statusRect.
  276.     //        // Will not move memory. //
  277. extern pascal void SBGetTotalModuleBounds(Rect *bounds, WindowRef stripPort, ModuleReference moduleRefNum)
  278.  TWOWORDINLINE(0x70FA, 0xAAF2);
  279.  
  280.     // returns the statusRect of the module.  Very useful for drag-n-drop routines
  281.     // because you no longer have to constantly set a global rectangle variable to
  282.     // hold the current location of the module in the Strip window.
  283.     //        // Will not move memory. //
  284. extern pascal void SBGetModuleBounds(Rect *bounds, ModuleReference moduleRefNum)
  285.  TWOWORDINLINE(0x70F9, 0xAAF2);
  286.  
  287. /* Miscellaneous Utilities */
  288.  
  289.     // runs this (locked!) piece of code once within Extensions Strip's context.
  290.     // PPC modules must pass a valid routine descriptor to this function.  Since
  291.     // the descriptor will not be disposed of after the code has executed, I would
  292.     // recommend creating the descriptor (NewSBQueueProcProc) when sdevInitModule
  293.     // is called and disposing it upon sdevCloseModule.
  294.     // A non-zero result code means that the UPP could not be queued (memory error).
  295.     //        // May move memory! //
  296. extern pascal OSErr SBQueueCode(SBQueueUPP theProc, unsigned long refCon)
  297.  TWOWORDINLINE(0x70F8, 0xAAF2);
  298.  
  299.     // sends the specified Apple Event within Extensions Strip's context to insure
  300.     // safe sending rather than trusting that the front application is AE aware.
  301.     // _SBSimpleAESend acts just like _AESend in that the AppleEvent you give to it
  302.     // must still be disposed of afterward by your code to free up memory (even
  303.     // though the event hasn't actually been sent yet.)
  304.     //
  305.     // _SBSimpleAESend is meant to be an easy way to send simple events.  If you
  306.     // need to check the reply AppleEvent or the _AESend error, ect., you should queue
  307.     // your code (with _SBQueueCode or by having your module return 'sdevQueueModule')
  308.     // and send the Apple Event yourself.  The result returned by _SBSimpleAESend
  309.     // is only non-zero if an error occured while queueing the event for later sending.
  310.     //
  311.     // Also, if an error does occur when Extensions Strip sends your AppleEvent, the
  312.     // user will be notified with a dialog that _AESend failed.
  313.     //
  314.     // Here are the parameters I give to _AESend.  They are basic enough for most
  315.     // kinds of Apple Events that modules send, hence the name _SBSimpleAESend.
  316.     // err = AESend(&theAppleEvent, &reply,                // your specified AppleEvent
  317.     //                                                    // and a dummy reply descriptor
  318.     //            kAENoReply + kAEAlwaysInteract + kAECanSwitchLayer,    // send mode
  319.     //            kAENormalPriority,                                    // send priority
  320.     //            kAEDefaultTimeout,                                    // time out
  321.     //            nil,                                                // idleProc
  322.     //            nil);                                                // filterProc
  323.     //        // May move memory! //
  324. extern pascal OSErr SBSimpleAESend(const AppleEvent *theAppleEvent)
  325.  TWOWORDINLINE(0x70F7, 0xAAF2);
  326.  
  327.     // returns a pointer to the current event being processed.  Modififations to
  328.     // the data in this pointer WILL take effect as the event gets passed along
  329.     // to the other processes and jGNE filters further on in the chain.  Although
  330.     // a module can use this function at any time, it is really meant to be called
  331.     // within the sdevInterceptedEvent selector because this is where a module can
  332.     // deny other modules the proper processing of the event (such as in the case
  333.     // of a keyDown.)  Another good use for SBGetCurrentEvent() is to find the exact
  334.     // point where a mouseDown occured if you have a queue of clickable objects.
  335.     //        // Will not move memory. //
  336. extern pascal EventRecord* SBGetCurrentEvent(void)
  337.  TWOWORDINLINE(0x70F6, 0xAAF2);
  338.  
  339.     // For Extensions Strip 1.2 and later.                                //
  340.     // Check for gestalt features bit 'gestaltHasSBResolveAliasFile'.    //
  341.  
  342.     // resolves a chain of alias files just like the toolbox routine ResolveAliasFile()
  343.     // but with an option to override the mounting of remote volumes.  Most of the code
  344.     // is from an Apple snippet in the Technote "Quietly Resolving Finder Aliases".
  345.     //
  346.     // Also, in the event of the display of an AppleShare mounting dialog, if the
  347.     // current process is not in front, then the front process will be set to the
  348.     // current one.  Since Extensions Strip 1.2 and later can only be run as regular
  349.     // applications, the use of this trap is almost always safe to display mount
  350.     // dialogs.  You should, however, set the mounting of remote volumes to false
  351.     // if called inside a drop handler when the current process is not the front one.
  352.     //        // May move memory! //
  353. extern pascal OSErr SBResolveAliasFileMountOption(FSSpec *fileFSSpec, Boolean resolveAliasChains,
  354.         Boolean *targetIsFolder, Boolean *wasAliased, Boolean mountRemoteVols)
  355.  TWOWORDINLINE(0x70F5, 0xAAF2);
  356.  
  357.  
  358. #if PRAGMA_IMPORT_SUPPORTED
  359. #pragma import off
  360. #endif
  361.  
  362. #if PRAGMA_ALIGN_SUPPORTED
  363. #pragma options align=reset
  364. #endif
  365.  
  366. #ifdef __cplusplus
  367. }
  368. #endif
  369.  
  370. #endif /* __EXTENSIONSSTRIP__ */
  371.